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AN 
1 jr23 
本 文档 适用 于 Gradle plugin 0.9 版 本 ， 所 以 可 能 和 我 们 1.0 之 前 介绍 的 老 版 本 有 所 不 同 。 


1.1 新 构建 系统 的 目标 


新 构建 系统 的 目标 是 : 


e 可 以 很 容易 的 重用 代码 和 资源 

e 可 以 很 容易 的 创建 应 用 的 衍生 版 本 ， 所 以 不 管 你 是 创建 多 个 apk， 还 是 不 同 功能 的 应 用 都 很 方便 
e 可 以 很 容易 的 配置 、 扩 展 以 及 自 定义 构建 过 程 

e 和 IDE 无 终 整 合 





1.2 Gradle 是 什么 


Grade 是 一 个 非常 优秀 的 构建 系统 工具 ， 人 允许 你 通过 插件 的 方式 创建 自 定 义 的 构建 逮 辑 
Gradle 的 以 下 特性 让 我 们 选择 了 它 : 


e 用 过 领域 专用 语言 (DSL) 描 述 和 控制 构建 逻辑 

e 构建 文件 基于 Groovy ， 并 且 可 以 组 合 使 用 各 种 定义 的 元 素 ， 然 后 通过 代码 来 控制 这 些 DSL 达 到 定制 逻辑 的 目的 
e 内 建 的 基于 Maven 或 者 Ivy 的 依赖 管理 

e 使 用 非常 灵活 ，Gradle 不 会 强制 实现 的 方式 ， 你 可 以 使 用 最 佳 实践 

e 插件 能 提供 DSL 以 及 API 为 构建 文件 使 用 

e 良好 的 工具 API 以 供 IDE 集成 
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2 要 求 


e Gradle 1.10 或 者 1.11 或 者 1.12， 并 且 使 用 0.11.1 版 本 的 插件 
e SDK with Build Tools 要 求 19.0.0， 有 些 功能 可 能 需要 更 新 的 版 本 


要 求 
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3 基础 工程 


一 个 Gradle 工 程 是 通过 名 字 叫 build.gradle 的 文件 描述 其 构建 过 程 的 ， 该 文字 位 于 工程 的 根 目 录 下 。 


基础 工程 





Android Gradle 插件 中 文 指南 


3.1 基本 的 build 文 件 


最 基本 的 Java 工 程 ， 其 buiid.gradie 非常 简单 : 
apply plugin: 'java' 


这 里 应 用 了 Gradle 提 供 的 Java 插 件 。 该 插件 提供 了 构建 和 测试 Java 应 用 所 需 的 一 些 东 西 。 


一 个 最 基本 的 Android 工 程 的 build.gradle 如 下 : 


buildscript { 
repositories ( 
mavenCentral() 


J 


dependencies ( 
classpath 'com.android.tools.build:gradle:0.11.1' 
) 
à 


apply plugin: 'android' 
android ( 


compileSdkVersion 19 
buildToolsVersion "19.0.0" 


f£ Android buid file 中 ， 有 3 个 主要 组 成 部 分 。 
buildscript ( ... ) 部 分 配置 了 驱动 构建 的 代码 。 


在 该 部 分 中 ， 定 义 配置 使 用 了 Maven 中 央 仓库 ， 并 且 声 明 依赖 一 个 Maven artifact( 构 件 ?)。 这 个 artifact 是 一 个 包含 0.11.1 
版 本 的 Android Gradle 插件 库 。 


注意 : 这 部 分 的 配置 只 会 影响 构建 过 程 的 代码 ， 和 你 的 工程 没有 关系 。 工 程 会 定义 它 自己 的 仓库 和 相关 依赖 。 稍 候 会 详细 介 


d. 


Nx 


接 下 来 ，android 插件 被 占用， 这 和 上 面 的 Java 插 件 是 一 样 的 。 
最 后 ， android { ... } 这 部 分 配置 了 android 构建 需要 的 所 有 参数 。 这 里 也 是 Android DSL 的 入 口 点 。 


默认 情况 下 ， 只 有 编译 的 目标 SDK、 构 建 工 具 的 版 本 是 必需 的 。 就 是 compilesdkversion 和 buildtoolsversion 两 个 配置 属 
性 。 


compilation target 和 旧 构 建 系 统 中 的 project.properties 文件 里 target 属性 是 一 样 的 。 这 个 新 的 属性 和 以 前 的 target 一 
样 ， 可 以 指定 一 个 int 类 型 ( api 级 别 ) 或 者 string 类 的 值 。 


重要 : 你 应 该 只 应 用 android 插件 就 好 了 ， 不 要 同时 应 用 java 插件 ， 因 为 这 会 导致 构建 错误 





注意 : 你 还 需要 在 同 目录 下 添加 一 个 /local.properties 文件 ， 并 通过 sdk.dir 属性 配置 所 需 的 SDK 的 路 径 。 除 此 之 外 ， 你 也 
可 以 设置 一 个 名 为 ANDROID Home 环境 变量 。 这 两 种 方法 都 差不多 ， 你 可 以 选择 自己 喜欢 的 。 
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口 
3.2 工程 结构 
上 面 说 的 build 文件 约定 了 一 个 默认 的 文件 夹 结构 。Gradle 遵循 约定 优先 于 配置 的 原则 ， 在 可 能 的 情况 下 提供 合理 的 默认 
值 。 
基本 的 工程 始 于 两 个 名 为 "Source sets" 的 部 分 。 也 就 是 main source code 和 test code。 他 们 分 别 位 于 : 


e Src/main 
e Src/androidTest/ 


里 面 的 每 一 个 文件 夹 都 对 应 相应 的 组 件 。 
对 于 Java 和 Android 这 两 个 插件 来 说 ， 他 们 的 Java 源 代码 和 Java 资 源 的 位 置 是 : 


e java/ 
e resources/ 


对 于 Android 插件 来 说 ， 它 还 有 以 下 特性 文件 和 文件 夹 : 


e AndroidManifest.xml 
e res/ 

e assets/ 

e aidl/ 

e rs/ 

e jni/ 


注意 : src/androidTest/AndroidManifest.xml 是 不 需要 的 ， 它 会 被 自动 创建 。 
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3.2.1 配置 结构 


当 默 认 的 工程 结构 不 适用 的 时 候 ， 你 可 能 需要 配置 它 。 根 据 Grade 文档 说 明 ， 可 以 通过 如 下 方式 重新 配置 Java 工 程 的 


sourceSets : 


sourceSets ( 
main ( 
java { 
srcDir 'src/java' 
J 
resources { 
srcDir 'src/resources' 


J 


注意 : srcpir 会 添加 指定 的 文件 夹 到 现 有 的 源 文 件 夹 列表 中 ( Gradle 文档 没有 提 到 这 个 ， 但 是 的 确 是 这 样 )。 


要 替换 默认 的 源 文件 夹 的 话 ， 可 以 给 srcpirs 指定 一 个 路 径 数组 。 下 面 使 用 对 象 调用 另 一 种 方式 配置 : 


sourceSets ( 
main.java.srcDirs - ['src/java'] 
main.resources.srcDirs - ['src/resources'] 


想 要 了 解 更 多 的 信息 ， 请 参考 Gradle 文 档 的 Java 插 件 部 分 。 
Android 插 件 也 使 用 相似 的 语法 ， 但 是 它 有 它 自己 的 sourceSets ,这 些 已 经 内 置 在 android 对 象 中 了 。 


这 儿 有 个 示例 ， 它 使 用 了 旧 工 程 结 构 的 源 代码 ， 并 且 重 新 映射 了 androidTest sourceSet 到 测试 文件 夹 : 


android { 
sourceSets { 

main { 
manifest.srcFile 'AndroidManifest.xml' 
java.srcDirs - ['src'] 
resources.srcDirs - ['src'] 
aidl.srcDirs - ['src'] 
renderscript.srcDirs - ['src'] 
res.srcDirs - ['res'] 
assets.srcDirs - ['assets'] 

J 


androidTest.setRoot('tests') 


注意 : 因为 旧 结 构 中 把 所 有 的 源 文件 ( java, aidl, renderscript, and java resources ) 都 放 在 同一 文件 夹 下 ， 所 以 我 们 需要 重新 
映射 这 些 sourceSet 的 新 组 件 到 同一 src 目 录 . 


注意 : setRoot() 方 法 会 移动 整个 sourceSet (包括 其 下 的 子 文件 夹 ) 到 一 个 新 文件 夹 。 这 里 是 移动 src/androidTest/* 到 tests/*。 


这 些 都 是 Android 特有 的 ， 并 不 适用 于 Java sourceSets 。 


及 


这 是 一 个 迁移 的 例子 ( 译 者 注 : 比如 从 旧 工 程 结构 迁移 过 来 )。 
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3.3 构建 任务 


3.3.1 通用 任务 


在 构建 文件 中 应 用 一 个 插件 的 时 候 会 自动 的 创建 一 系列 可 运行 的 构建 任务 。Java plugin 和 the Android plugin 都 可 以 做 到 这 
一 点 。 以 下 是 约定 的 一 些 任务 : 


e assemble 这 个 任务 会 汇集 工程 的 所 有 输出 。 

e check 这 个 任务 会 执行 所 有 校 验 检查 

e build 这 个 任务 会 同时 执行 assemble 和 check 任务 
e clean 这 个 任务 会 清理 工程 的 所 有 输出 


事实 上 ，assemble , check 以 及 build 这 三 个 任务 并 没有 作 任 何事 情 ， 他 们 只 是 插件 的 引导 任务 ， 引 导 揪 件 添加 的 其 他 任 
务 去 完成 一 些 工作 。 


这 样 就 可 以 允许 你 调用 同样 的 任务 ， 而 不 用 管 它 是 什么 类 型 的 工程 或 者 应 用 了 什么 插件 。 





比如 ， 应 用 加 dbugs 插件 会 创建 一 个 任务 ， 并 且 让 check 任务 依赖 它 ， 这 样 当 这 个 check 任务 被 调用 的 时 候 ， 这 个 新 创建 
的 任务 也 会 被 调用 . 


在 命令 行 中 输入 如 下 命令 可 以 获取 一 些 高 级 别 的 任务 介绍 。 


gradle tasks 


要 查看 所 有 的 任务 列表 以 及 任务 之 间 的 依赖 关系 运行 : 


gradle tasks --all 


注意 : Gradle 会 自动 监控 任务 定义 的 输入 和 输出 。 


不 做 任何 改变 两 次 运行 build ，Gradle 会 报告 所 有 任务 已 经 处 于 UP-TO-DATE 状态 ， 这 意味 着 没有 什么 可 做 的 。 这 使 得 任 
务 之 间 可 以 正确 的 相互 依赖 ， 又 不 会 导致 其 他 不 需要 的 操作 执行 。 














E 
EN 
E 
$ 
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3.3.2 Java 工程 任务 
Java plugin 创建 了 两 个 主要 的 任务 ， 主 要 的 引导 任务 都 依赖 他 们 。 
e assemble 
o jar 这 个 任务 创建 所 有 输出 
e check 


o test 这 个 任务 运行 所 有 测试 


jar 任务 直接 或 者 间接 的 依赖 其 他 任务 : 比如 classes 会 编译 所 有 Java 代 码 . 


testClasses 会 编译 所 有 测试 ， 但 是 它 很 少 使 用 ， 因 为 test 这 个 任务 依赖 它 (和 classes 差不多 )。 


通常 情况 下 ， 你 可 能 只 用 到 assemble 或 者 check ,其 他 的 任务 不 会 使 用 。 


你 可 以 在 这 儿 看 到 Java plugin 的 所 有 任务 列表 以 及 他 们 的 依赖 关系 


Java 工 程 任务 











12 


Android Gradle 插件 中 文 指南 


3.3.3 Android 任务 
Android plugin 使 用 了 同样 的 约定 规则 以 和 其 他 插件 保持 兼容 ， 并 且 又 添加 了 一 些 额外 的 引导 任务 : 


e assemble 这 个 任务 会 汇集 工程 的 所 有 输出 。 

e check 这 个 任务 会 执行 所 有 校 验 检查 

e connectedCheck 运行 checks 需要 一 个 连接 的 设备 或 者 模拟 器 ， 这 些 checks 将 会 同时 运行 在 所 有 连接 的 设备 上 。 
e deviceCheck 通过 API 连接 远程 设备 运行 checks。 它 被 用 于 CI ( 译 者 注 :持续 集成 ) 服 务 器 上 。 

e build 这 个 任务 会 同时 执行 assemble 和 check 任务 

e clean 这 个 任务 会 清理 工程 的 所 有 输出 


这 些 新 的 引导 任务 是 必须 的 ， 以 便 能 够 在 没有 连接 的 设备 的 情况 下 运行 定期 检查 。 


注意 build 既 不 依赖 deviceCheck ,也 不 依赖 connectedCheck 。 


一 个 Android 工 程 至 少 有 两 个 输出 :一 个 debug APK 和 一 个 release APK。 他 们 每 一 个 都 有 自己 的 引导 任务 以 便 可 以 单独 的 构 


建 他 们 : 


e assemble 
o assembleDebug 
o assembleRelease 


他 们 两 个 都 依赖 其 他 任务 ， 这 些 任 务 执行 很 多 必须 的 步骤 以 生成 一 个 APK。 assemble 任务 又 依赖 他 们 两 个 ， 所 以 执行 
assemble 会 生成 两 个 APK。 


提示 : ERDI TF, Grade 支持 任务 名 称 驼峰 方式 的 快捷 调用 ， 比 如 : 


gradle aR 


和 


gradle assembleRelease 


是 一 样 的 ， 当 然 前 提 是 没有 其 他 任务 匹配 'aR'。 
检验 引导 任务 也 有 他 们 自己 的 依赖 : 


e check 
o lint 
e connectedCheck 
o connectedAndroidTest 
o connectedUiAutomatorTest (尚未 实现 ) 
e deviceCheck 
o 这 个 依赖 其 他 插件 创建 的 时 候 实现 的 测试 扩展 点 的 哪些 任务 。 


最 后 ， 插 件 会 为 所 有 的 构建 类 型 ( debug, release, test ) 创 建 install/uninstall 任务 ， 也 只 有 他 们 能 被 安装 (需要 签名 ) 。 


Android 任 务 
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rt. 
3.4 自 定义 构建 
Android plugin 提供 了 大 量 的 DSL 能 够 让 你 直接 基于 构建 系统 定制 很 多 事情 。 


3.4.1 Manifest 选 项 
通过 DSL 可 以 配置 manifest 的 如 下 选项 : 


e minSdkVersion 

e targetSdkVersion 

e versionCode 

e versionName 

e applicationld (更 有 效 的 packageName -- 请 看 Applicationld 与 PackageName 获 取 更 多 信息 ) 
e Package Name for the test application 

e Instrumentation test runner 


示例 : 


android { 
compileSdkVersion 19 
buildToolsVersion "19.0.0" 


defaultConfig { 
versionCode 12 
versionName "2.0" 
minSdkVersion 16 
targetSdkVersion 16 


android 元 素 里 的 defaultConfig 负责 定义 所 有 的 配置 。 


Android Plugin 以 前 的 版 本 是 使 用 packageName 配置 manifest 的 'packageName' 属 性 。 从 0.11.0 开始 ， 你 应 该 在 
build.gradle 里 使 用 applicationld 来 配置 manifest 的 'packageName' 属 性 。 这 是 为 了 消除 应 用 的 packageName (也 就 是 
ID) 和 java 的 packages 之 间 的 歧义 。 


通 
RA 


T 


def computeVersionName() { 


» 


android ( 
compileSdkVersion 19 
buildToolsVersion "19.0.0" 


defaultConfig { 
versionCode 12 
versionName computeVersionName() 
minSdkVersion 16 
targetSdkVersion 16 


注意 : 不 要 使 用 在 给 定 的 范围 内 ， 和 其 他 已 经 存在 的 getters 方法 冲突 的 方法 名 字 。 比 如 在 defaultconfig ( ...) 中 调用 
getVersionName() 方法 会 自动 的 调用 defaultconfig.getversionName() 方法 ， 如 果 你 也 自 定义 一 个 这 样 的 名 字 的 方法 ， 那 么 


Manifest 选 项 


过 build 文 件 定义 的 强大 之 处 在 于 可 以 动态 的 被 配置 。 比如 ， 可 以 从 一 个 文件 读 取 版 本 名 字 ， 或 者 使 用 一 些 其 他 的 自 定义 的 
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你 的 方法 不 会 调用 。 





如 果 一 个 属性 没有 通过 DSL 设 置 ， 则 会 使 用 它们 的 默认 值 。 这 里 有 个 表格 说 明 是 如 何 处 理 的 。 


versionCode 


versionName 


minSdkVersion 


targetSdkVersion 


applicationld 


testApplicationld 


testlnstrumentationRunner 


signingConfig 


proguardFile 


proguardFiles 


DSL 对 象 的 默认 值 默认 值 
4 如 有 有 的 话 从 manifest 中 读 取 
null 如 有 有 的 话 从 manifest 中 读 取 
4 如 有 有 的 话 从 manifest 中 读 取 
4 如 有 有 的 话 从 manifest 中 读 取 
null 如 有 有 的 话 从 manifest 中 读 取 
null applicationld + ".test" 
null android.test.InstrumentationTestRunner 
null null 
N/A (只 能 设置 ) N/A (只 能 设置 ) 
N/A (只 能 设置 ) N/A (只 能 设置 ) 


如 果 你 在 构建 脚本 中 使 用 自 定义 的 逻辑 获取 这 些 属性 的 时 候 ， 那 么 第 二 列 的 值 尤其 重要 。 上 比如 ， 你 可 能 这 样 写 : 


if (android.defaultConfig.testInstrumentationRunner == null) { 
// assign a better default... 


} 


如 果 值 一 直 为 null， 那 么 在 构建 的 时 候 ， 它 将 会 被 从 第 三 列 中 获取 的 实际 的 默认 值 替 换 ， 但 是 在 DSL 元 素 中 又 不 包含 这 个 默 


认 值 ， 所 以 你 无 法 查询 到 它 。 


Manifest 选 项 


这 是 为 了 防止 解析 应 用 的 manifest 文件 ， 除 非 真 的 需要 。 
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3.4.2 构建 类 型 


默认 情况 下 ，Android plugin 会 自动 的 设置 工程 ， 构 建 release 和 debug 两 个 版 本 。 他 们 主要 的 差异 主要 在 于 是 否 可 以 在 设 
备 上 调试 应 用 以 及 APK 如 何 签名 。 


debug 版 本 会 被 使 用 已 知 的 名 称 /密码 自动 生成 的 密 钥 /证 书签 名 。release 版 本 在 构建 过 程 中 不 会 被 签名 ， 需 要 构建 后 再 签 


名 。 


这 些 配置 可 以 通过 一 个 叫 BuildType 配置 。 默 认 情 况 下 ， 已 经 创建 了 debug 和 release 这 两 个 实例 。 





Android plugin 允许 自 定义 这 两 个 示例 ， 并 且 可 以 创建 其 他 的 Build Types 。 这 些 是 可 以 在 buildTypes DSL 容 器 中 配置 完成 : 


android { 
buildType 
debug 
a 


} 


jnide 
jnide 


st 
it 
pplicationIdSuffix ".debug" 


bug.initwWith(buildTypes.debug) 
bug ( 


packageNameSuffix ".jnidebug" 
jniDebuggable true 


以 上 的 片段 实现 了 以 下 几 点 : 


e 配置 了 默认 的 debug 构建 类 型 : 


o 设置 包 名 为 «app appliationid».debug 以 便 可 以 在 同一 设备 上 同时 安装 debug 和 release 两 个 版 本 的 APK 





e 创建 一 个 叫 jnidebug 新 的 Build Types ， 并 且 配 置 它 作为 debug 构建 类 型 的 一 个 副本 
e 然后 再 配置 jnidebug ， 启 用 JNI 组 件 的 debug 构建 ， 并 且 添 加 一 个 不 同 的 包 名 后 级 


创建 一 个 新 的 Build Types 很 简单 ， 只 需要 在 buildTypes 容器 下 添加 一 个 元 素 ， 然 后 调用 initWith() 或 者 使 用 一 个 闭 包 配置 


(m 





这 里 有 一 些 可 能 用 到 的 属性 以 及 他 们 的 默认 值 : 


属性 名 debug 时 的 默认 值 
debuggable true 
jniDebuggable false 
renderscriptDebuggable false 
renderscriptOptimLevel 3 
applicationldSuffix null 
versionNameSuffix null 


signingConfig 


android.signingConfigs.debug 


zipAlignEnabled false 
minifyEnabled false 
proguardFile N/A (只 能 设置 ) 
proguardFiles N/A (只 能 设置 ) 





release 或 者 其 他 类 型 的 默认 值 


false 


false 


false 
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除了 这 些 属性 外 ， 代码 和 资源 也 会 影响 到 Build Types. 对 于 每 一 个 Build Type, 都 会 创建 一 个 新 的 匹配 的 sourceSet ， 默 认 
位 置 是 


src/«buildtypename»/ 


这 意味 着 Build Type 的 名 字 不 能 是 main 和 androidTest (这 两 个 已 经 被 插件 占用 )， 并 且 他 们 相互 之 间 的 名 字 必 须 唯 一 。 


和 其 他 的 source sets 一 样 ，Build Type 的 source set 的 位 置 可 以 被 重 定向 : 


android ( 
sourceSets.jnidebug.setRoot('foo/jnidebug') 


J 


此 外 ， 对 于 每 一 个 Build Type ， 都 会 新 创建 assemble\ 任 务 。 


assembleDebug 和 assembleRelease 这 两 个 任务 已 经 讲 过 了 ， 这 里 讲 的 是 他 们 是 从 哪 来 的 。 是 在 debug 和 release 这 两 
个 Build Types 被 预先 创建 的 时 候 。 


提示 : 记得 你 可 以 通过 输入 gradle aJ 来 运行 assembleJnidebug 任 务 哦 。 
可 能 使 用 到 的 情况 : 

e 在 debug 模式 下 需要 ， 但 是 在 release 下 不 需要 的 权限 

e 自 定义 debug 的 实现 

e 微 debug 默认 使 用 不 同 的 资源 〈 比 如 一 个 资源 的 值 是 由 签名 的 证 书 决定 的 ) 
BuildType 的 代码 /资源 主要 通过 以 下 方式 使 用 : 


e manifest 被 合并 进 app 的 manifest 

e 代码 仅仅 是 作为 一 个 额外 的 source 文件 夹 ( 译 者 注 : 其 实 和 自己 新 建 一 个 source 文件 夹 ， 然 后 在 这 个 文件 夹 下 新 建 包 和 
类 一 样 ) 

e 资源 会 覆盖 mai 里 的 资源 ， 蔡 换 现 有 的 值 
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3.4.3 签名 配置 
要 对 一 个 应 用 签名 ， 要 求 如 下 : 


e 一 个 keystore 

e 一 个 keystore 的 密码 
e 一 个 key 的 别名 

e 一 个 key 的 密码 

e 存储 类 型 


fri]. key 914. key 密码 以 及 存储 类 型 一 起 组 成 了 签名 配置 ( SigningConfig 类 型 ) 


默认 情况 下 ， 已 经 有 了 一 个 debug 的 签名 配置 ， 它 使 用 了 debug keystore， 该 keystore 有 一 个 已 知 的 密码 和 默认 的 带 有 已 
知 密码 的 key, debug keystore 位 于 $HOME/.android/debug.keystore， 如 果 没 有 会 被 创建 。 


debug Build Type 被 设置 为 自动 使 用 debug 签名 配置 。 


你 也 可 以 创建 其 他 的 签名 配置 或 者 自 定义 内 置 的 配置 。 可 以 通过 signingConfigs DSL 容 器 实现 。 


android { 
signingConfigs { 
debug { 
storeFile file("debug.keystore") 
J 


myConfig (ss 
storeFile file("other.keystore") 
storePassword "android" 
keyAlias "androiddebugkey" 
keyPassword "android" 


m 


buildTypes ( 
foo ft 
debuggable true 
jniDebuggable true 
signingConfig signingConfigs.myConfig 


以 上 片段 会 把 debug keystore 的 路 径 改 为 工程 的 根 目 录 。 这 会 自动 的 影响 任何 用 到 它 的 Build Types ， 在 这 里 影响 到 的 是 
debug Build Type 。 


以 前 片段 也 创建 了 一 个 新 的 签名 配置 ， 并 且 被 一 个 新 的 Build Type 使 用 。 

注意 : 只 有 默认 路 径 下 的 debug keystores 才 会 被 自动 创建 。 如 果 改 变 了 debug keystore 的 路 径 将 不 会 在 需要 的 时 候 创 建 。 
一 个 使 用 不 同名 字 的 SigningConfig ， 但 是 用 的 是 默认 的 debug keystore 路 径 的 话 是 会 被 自动 创建 的 。 也 就 是 说 ， 会 不 

会 被 自动 创建 ， 和 keystore 的 路 径 有 关 ， 和 配置 的 名 字 无 关 。 


说 明 : 通常 情况 下 ， 会 使 用 工程 根 目录 的 相对 路 径 作 为 keystores 的 路 径 ， 但 有 时 候 也 会 用 绝对 路 径 ， 虽 然 这 并 不 推荐 (被 自 
动 创 建 的 debug keystore 除外 )。 


注意 : 如 果 已 经 你 将 这 些 文件 放 到 版 本 控制 中 ， 你 可 能 不 想 把 密码 存储 在 文件 中 。Stack Overflow 上 有 个 帖子 介绍 可 以 从 控 
制 台 或 者 环境 变量 中 获取 这 些 密码 等 信息 。 


http://stackoverflow.com/questions/18328730/how-to-create-a-release-signed-apk-file-using-gradle 
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我 们 以 后 更 新 这 个 指南 的 时 候 会 添加 更 多 的 信息 。 


签名 配置 
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3.4.4 使 用 混淆 


自从 Gradle plugin for ProGuard 4.10 版 本 以 后 ，Gradle 开始 支持 混淆 。 如 果 通 过 Build Type 的 minifyEnabled 属性 配置 了 


使 用 混淆 后 ，The ProGuard plugin 会 自动 被 上 应用， 并且 自动 创建 一 些 任务 。 


android { 
buildTypes { 
release ( 
minifyEnabled true 
proguardFile getDefaultProguardFile( 'proguard-android.txt') 
y 
J 
productFlavors { 
flavori ( 
i 
flavor2 { 


proguardFile 'some-other-rules.txt' 


J 


使 用 buildTypes 以 及 productFlavors 定义 的 规则 文件 可 以 轻松 的 生成 多 种 版 本 。 
有 两 个 默认 的 规则 文件 


e proguard-android.txt 
e proguard-android-optimize.txt 


他 们 位 于 SDK 中 ， 使 用 getpefaultProguardFile() 方法 可 以 返回 文件 的 全 路 经 。 除 了 是 否 启用 优化 之 外 ， 这 两 个 文件 的 其 他 


功能 都 是 相同 的 。 








使 用 混淆 
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3.4.5 清理 资源 


在 构建 的 时 候 ， 你 也 可 以 自动 的 移 除 一 些 未 使 用 的 资源 。 更 多 信息 ， 


清理 资源 
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4 


依赖 ，Android 库 工程 以 及 多 工程 设置 


Gradle 可 以 依赖 其 他 的 一 些 组 件 ， 这 些 组 建 可 以 是 外 部 二 进 制 包 ， 也 可 以 是 其 他 Grade 工程 。 


4.1 依赖 二 进 制 包 





4.1.1 本 地 包 


要 配置 依赖 一 个 外 部 库 jar 包 ， 你 可 以 在 compile 配置 里 添加 一 个 依赖 。 


n 
"s 


dependencies { 
compile files('libs/foo.jar') 


J 


android { 


J 





: dependencies DSL 元 素 是 标准 Gradle API 的 一 部 分 ， 并 不 属于 android 的 元 素 。 


compile 配置 用 来 编译 main application， 它 里 面 的 一 切 都 会 被 添加 到 编译 的 classpath 中 ， 并 且 也 会 被 打包 到 最 终 的 APK 
中 。 


这 里 还 有 添加 依赖 时 其 他 的 配置 : 


compile : main application 
androidTestCompile : test application 
debugCompile : debug Build Type 
releaseCompile : release Build Type 


因为 要 构建 生成 一 个 APK， 必 然 会 有 相关 联 的 Build Type ，APK 默 认 配置 了 两 个 (或 者 更 多 ) 编 译 配 置 : compile 和 \Compile。 
创建 一 个 新 的 Build Type 的 时 候 会 自动 创建 一 个 基于 它 名 字 的 编译 配置 。 


当 一 个 debug 版 本 需要 一 个 自 定 义 库 ( 比 如 报告 崩溃 )， 但 是 release 版 本 不 需要 或 者 需要 一 个 不 同 版 本 的 库 的 时 候 ， 会 显得 
非常 有 用 。 
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4.1.2 远程 artifacts 
Gradle 支持 从 Maven 和 Ivy 仓库 获取 artifacts。 


首先 必须 把 库 添 加 到 列表 中 ， 并 且 以 Maven 或 者 Ivy 的 定义 方式 定义 需要 的 依赖 。 


repositories { 
mavenCentral() 


} 


dependencies { 
compile 'com.google.guava:guava:11.0.2' 


» 


android { 


J 


注 : mavenCentral() 是 指定 仓库 URL 的 快捷 方式 。Gradle 同时 支持 远程 和 本 地 两 种 仓库 注 
这 就 意味 着 如 果 依 赖 本 身 会 依赖 其 他 东西 ， 这 些 也 会 被 拉 取 过 来 。 


更 多 关于 dependencies 的 设置 信息 ， 请 参见 Gradle 用 户 指 南 ， 以 及 DSL 文 档 


远程 artifacts 


: Gradle 遵循 依赖 的 传递 性 。 
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4.2 多 工程 设置 


Gradle 工程 可 以 通过 多 工程 配置 依赖 其 他 的 Gradle 工 程 





多 工程 配置 通常 把 所 有 的 工程 作为 根 目录 的 子 文件 夹 。 


比如 ， 下 面 的 工程 结构 : 


MyProject/ 
app/ 
libraries/ 

libi/ 
lib2/ 


我 们 可 以 识别 这 三 个 工程 。Gradle 会 通过 如 下 名 字 引 用 他 们 : 


:app 
:libraries:libi 
:libraries:lib2 


每 个 工程 都 有 属于 它 自己 的 build.gradle 文件 定义 如 何 构建 它 自己 。 
此 外 ， 在 工程 根 目录 下 有 个 叫 settings.gradle 的 文件 会 定义 所 有 工程 。 


文件 结构 如 下 : 


MyProject/ 
settings.gradle 
app/ 

build.gradle 
libraries/ 
libi/ 
build.gradle 
lib2/ 
build.gradlef 


settings.gradle 里 的 内 容 非 常 简 单 : 


include ':app', ':libraries:lib1', ':libraries:lib2' 


这 里 定义 了 哪个 文件 是 一 个 Gradle 工 程 。 
:app 工程 也 可 能 会 依赖 一 些 库 工 程 ， 可 以 通过 如 下 脚本 声明 依赖 : 
dependencies { compile project(":libraries:lib1') } 


更 多 关于 多 工程 的 配置 请 参考 这 里 





多 工程 设置 
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4.3 库 工 程 


在 上 面 的 多 工程 配置 中 ，:libraries:lib1 和 :libraries:lib2 可 能 是 Java 工 程 ， 并 且 :app Android 工 程 会 用 到 他 们 生成 的 jar 
报 。 


但 是 ， 如 果 你 想 共 享 访 问 Android API 的 代码 或 者 使 用 Android 的 样式 资源 ， 那 么 这 个 库 工程 就 不 能 是 通常 的 Java 工程 ， 而 
应 该 是 Android E Tf, 


4.3.1 创建 一 个 库 工 程 
一 个 Android 库 工 程 和 一 个 Android 工程 非常 相似 ， 只 有 一 点 差别 。 


因为 构建 一 个 库 和 构建 一 个 应 用 不 太一 样 ， 所 以 它 使 用 了 一 个 不 同 的 插件 。 这 两 个 插件 (构建 应 用 和 库 的 ) 大 部 分 代码 都 是 一 
样 ， 并 且 都 是 通过 com.android.tools.build.gradle jar 包 提 供 。 


buildscript { 
repositories ( 
mavenCentral() 


J 


dependencies ( 
classpath 'com.android.tools.build:gradle:0.5.6"' 
} 


apply plugin: 'android-library' 


android ( 
compileSdkVersion 15 


} 


这 里 创建 一 个 基于 API 15 级 别 编 译 的 库 工程 。SourceSets ， 以 及 依赖 的 义理 方式 和 应 用 工程 是 一 样 并 且 可 以 以 同样 的 方式 
进行 自 定 义 。 
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4.3.2 普通 工程 和 库 工 程 的 不 同 


库 工程 的 main 输出 是 一 个 .aar 报 ( 这 个 一 个 标准 的 Android 存档 ). 它 由 编译 后 的 代码 (比如 jar 文件 或 者 .so 文件 ) 以 及 资源 
文件 ( manifest, res, assets ) 组 成 。 


库 工程 也 可 以 生成 一 个 测试 apKk， 可 以 独立 于 应 用 进行 测试 。 
它 有 相同 的 引导 任务 (assembleDebug , assembleRelease )， 所 以 他 和 一 般 的 工程 没有 什么 不 同 。 
其 余 的 ， 基 本 上 都 和 应 用 一 样 了 。 他 们 都 有 build types 和 product flavors， 可 以 生成 多 个 版 本 的 aar. 


注意 Build Type 大 部 分 配置 并 不 适用 于 库 工 程 。 不 过 你 可 以 依据 库 工 程 是 被 其 他 工程 依赖 还 是 测试 ， 然 后 通过 自 定 义 库 工 程 
sourceSet 改变 它 的 内 容 。 





1% 


通 工 程 和 库 工 程 的 区 别 26 











Android Gradle 插件 中 文 指南 


4.3.3 引用 一 个 库 工 程 


引用 一 个 库 工 程 和 引用 其 他 工程 是 一 样 的 : 


dependencies { 
compile project(':libraries:lib1') 
compile project(':libraries:lib2') 


说 明 : 如 果 你 有 多 个 依赖 库 工 程 ， 顺序 是 
的 。 








引用 一 个 库 工 程 














很 重要 的 。 这 和 旧 构 建 系 统 中 在 project.properties 文件 中 定义 的 依赖 顺序 是 一 样 
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4.3.4 库 工 程 发 布 





默认 情况 下 库 工程 只 能 发 布 release 版 本 。 这 个 版 本 用 于 所 有 工程 的 引用 ， 和 工程 本 身 要 构建 什么 样 的 版 本 无 关 。 这 是 属于 
Gradle 的 限制 ， 我 们 正在 努力 消除 这 个 限制 。 


你 可 以 通过 如 下 方式 控制 发 布 的 各 种 版 本 


android { 
defaultPublishConfig "debug" 
J 


注意 这 里 的 发 布 配 置 的 名 字 使 用 的 是 一 个 完整 的 版 本 名 字 。 Release 和 debug 仅仅 适用 于 没有 其 他 版 本 的 时 候 使 用 。 如 果 你 
想 用 其 他 版 本 代 蔡 默认 发 布 的 版 本 ， 你 可 以 这 么 做 : 


android { 
defaultPublishConfig "flavoriDebug" 
J 


发 布 库 工程 的 所 有 不 同 版 本 也 是 可 能 的 。 我 们 计划 在 在 一 般 的 工程 对 工程 依赖 中 (就 像 上 面 说 的 ) 人 允许 这 么 做 。 但 是 这 还 不 被 
Gradle 人 允许 (我 么 正在 努力 修复 这 个 问题 )。 


默认 情况 下 ， 没 有 和 启用 发 布 所 有 不 同 的 版 本 功能 ， 你 可 以 这 人 么 启用 他 们 : 


android ( 
publishNonDefault true 
J 


要 意识 到 ， 发 布 多 个 不 同 的 版 本 意味 着 会 有 多 个 aar 文件 ， 而 不 是 一 个 aar 文件 中 包含 多 个 不 同 的 版 本 。 每 个 aar 包 只 包含 一 
个 版 本 。 发 布 一 个 版 本 意味 着 要 生成 一 个 可 用 的 aar 文件 作为 Grade 工程 的 输出 构件 。 它 既 可 以 被 发 不 到 一 个 maven 仓 
库 ， 也 可 以 被 其 他 工程 依赖 引用 。 


Gradle 有 默认 ' 构 件 ' 的 概念 ， 当 作 如 下 配置 时 会 用 到 : 


compile project(':libraries:lib2') 


要 创建 另外 一 个 已 发 布 构建 的 依赖 ， 你 需要 指定 需要 哪 一 个 : 


dependencies { 
flavoriCompile project(path: ':libi', configuration: 'flavoriRelease') 
flavor2Compile project(path: ':libi', configuration: 'flavor2Release') 


重要 : 注意 发 布 配置 的 是 一 个 完整 的 版 本 ， 包 括 build type， 并 且 需 要 像 上 面 一 样 被 引用 。 


重要 : 当 启 用 了 非 默认 发 布 的 时 候 ，Maven 的 发 布 插件 将 会 发 布 其 他 版 本 作为 扩展 包 〈 按 分 级 ) 。 这 意味 着 和 maven 上 的 
版 本 不 一 定 兼容 。 你 应 该 发 布 一 个 单独 的 版 本 到 仓库 中 或 者 为 工程 间 的 依赖 启用 所 有 的 发 布 配置 。 
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5 测试 
构建 的 测试 应 用 已 经 被 集成 在 应 用 工程 里 ， 不 需要 再 创建 一 个 单独 的 测试 工程 。 


5.1 基础 介绍 和 配置 


正如 上 面 讲 到 的 ， main sourceSet 的 旁边 就 是 androidTest sourceSet ， 默 认 的 路 径 是 src/androidTest/ 从 这 个 sourceSet 
可 以 构建 一 个 能 安装 到 设备 上 的 测试 apk， 该 apk 使 用 Android 测试 框架 测试 应 用 。 这 里 包括 单元 测试 、 集 成 测试 以 及 后 续 
的 UI 自动 化 测试 。 这 个 测试 sourceSet 不 必 包 含 AndroidManifest.xml 文件 ， 为 它 会 自动 生成 。 


测试 应 用 有 如 下 值 可 以 配置 : 


e testPackageName 
e testinstrumentationRunner 
e testHandleProfiling 
e testFunctionalTest 


如 前 所 见 ， 这 些 可 以 在 defaultConfig 对 象 里 配置 。 


android ( 
defaultConfig { 
testPackageName "com.test.foo" 
testInstrumentationRunner "android.test.InstrumentationTestRunner" 
testHandleProfiling true 
testFunctionalTest true 


在 测试 应 用 的 manifest xp, instrumentation 节点 的 targetPackage 属性 值 会 自动 的 被 测试 应 用 的 包 名 填充 ， 即 使 是 通过 
defaultConfig 或 者 Build Type 对 象 定 义 的 。 这 也 是 manifest 文件 自动 生成 的 一 个 原因 。 


此 外 ，sourceSet 也 可 以 配置 它 自己 的 依赖 。 默认 情况 下 ， 应 用 以 及 它 自己 的 依赖 会 被 添加 测试 应 用 的 classpath 中 ， 但 是 
也 可 以 进行 扩展 


dependencies { 
androidTestCompile 'com.google.guava:guava:11.0.2' 


} 


测试 应 用 通过 assembleTest 任务 来 构建 。 它 并 不 依赖 main 的 assemble 任务 ， 并 且 不 能 自动 调用 ， 需 要 手动 运行 。 


当前 只 能 同时 测试 一 个 Build Type, $Æ debug Build Type ， 但 是 也 可 以 被 重新 配置 


android { 


testBuildType "staging" 
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5.2 运行 测试 


正如 前 面 所 提 到 的 ， 引 导 任 务 connectedCheck 需要 一 个 已 经 连接 的 设 各 才能 运行 。 这 会 依赖 androidTest ， 所 以 
androidTest 也 会 被 运行 。 这 个 任务 做 了 以 下 事情 : 


e 确保 应 用 和 测试 应 用 已 经 被 构建 (依赖 assembleDebug 和 assembleTest ) 
e 安装 这 两 个 应 用 

e 运行 测试 

e 卸 着 这 两 个 应 用 


如 果 同 时 有 多 个 连接 的 设备 ， 那 么 所 有 的 测试 会 在 所 有 的 设备 上 运行 。 不 管 在 哪个 设备 上 ， 只 要 有 一 个 测试 失败 ， 那 么 整个 
构建 就 是 失败 的 。 


所 有 的 测试 结果 已 XML 的 格式 被 存储 在 build/androidTest-results 目录 下 。( 这 类 似 于 jUnit , 它 的 结果 存储 在 build/test-results 
目录 下 ) 





当然 ， 你 可 以 自己 设置 


android ( 


testOptions ( 
resultsDir = "$project.buildDir/foo/results" 


J 


android.testOptions.resultsDir 的 值 是 通过 Project.file(String) 得 到 。 
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5.3 测试 Android 库 


测试 Android 库 工 程 的 方式 和 应 用 工程 是 一 样 。 

仅 有 的 不 同 就 是 整个 库 ( 包 括 它 的 依赖 ) 会 作为 一 个 依赖 库 被 自动 的 添加 到 测试 应 用 中 。 测 试 APK 的 测试 结果 不 仅 包括 它 自己 
代码 的 测试 ， 还 包括 Android 库 的 以 及 库 的 所 有 依赖 的 测试 。 库 的 manifest 被 合并 到 测试 应 用 的 manifest 中 (这 种 情况 就 和 
任何 工程 引用 这 个 库 是 一 样 的 ) 

androidTest 任务 的 职责 也 不 一 样 了 ， 它 仅仅 负责 安装 (和 介 载 ) 测 试 APK (因为 也 没有 其 他 APK 需 要 安装 ) 


其 他 的 都 和 测试 应 用 差不多 。 
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5.4 测试 报告 


当 运 行 单元 测试 的 时 候 ，Gradle 会 生成 一 份 HTML 报告 以 便于 查看 测试 结果 。 Android plugins 在 这 个 基础 上 扩展 了 HTML 


报告 ， 以 合并 所 有 已 连接 设备 上 的 测试 结果 。 
5.4.1 单 工 程 报 告 
在 运行 测试 的 时 候 工程 会 自动 的 生成 报告 ， 默 认 位 置 是 : 


build/reports/androidTests 


这 和 jUnit 报告 的 位 置 build/reports/tests 很 相似 ， 其 他 报告 的 位 置 通 常 是 build/reportsNV 
报告 的 位 置 也 可 以 自 定义 
android ( 


testOptions ( 
reportDir = "$project.buildDir/foo/report" 


) 
) 
报告 会 合并 运行 在 不 同 设 备 上 的 测试 结果 。 


单 工程 报告 
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5.4.2 多 工程 报告 


在 一 个 既 有 应 用 工程 又 有 库 工 程 的 多 工程 里 ， 当 在 同时 运行 所 有 测试 的 时 候 ， 生 成 一 个 包含 所 有 测试 结果 的 报告 是 非常 有 用 
的 。 


为 了 达到 这 一 目的 ， 需 要 同一 构件 中 的 另外 一 个 插件 ， 可 以 通过 如 下 方式 应 用 : 


buildscript 1 
repositories ( 
mavenCentral() 


J 


dependencies ( 
classpath 'com.android.tools.build:gradle:0.5.6"' 
J 
J 


apply plugin: 'android-reporting' 


这 应 该 被 应 用 到 根 目 录 下 ,也 就 是 和 settings.gradle 相 邻 的 build.gradle 文件 中 . 


然后 ,在 根 目录 打开 终端 ,输入 如 下 命令 运行 所 有 测试 并 且 收 集 报告 
gradle deviceCheck mergeAndroidReports --continue 


XE: --continue 选项 确保 所 有 测试 都 被 执行 ,即使 测试 是 失败 的 .否则 的 话 第 一 个 失败 的 测试 会 中 断 运行 ,那么 就 可 能 会 有 一 些 
工程 的 测试 不 会 被 运行 
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5.5 Lint 支 持 


从 0.7.0 版 本 之 后 ,你 可 以 为 一 个 特定 的 变种 版 本 运行 lint ,也 可 以 为 所 有 变种 版 本 都 运行 .在 这 种 情况 下 , 它 会 产生 一 个 报告 指出 
给 定 的 变种 版 本 的 问题 . 


你 可 以 像 下 面 一 样 通过 lintOptions 自 定 义 lint .一 般 情况 下 ,你 只 需要 配置 其 中 的 一 部 分 .以 下 是 展示 所 有 可 用 的 lint 配置 项 . 


android ( 
lintoptions { 


// set to true to turn off analysis progress reporting by lint 

quiet true 

// if true, stop the gradle build if errors are found 

abortOnError false 

// if true, only report errors 

ignorewarnings true 

// if true, emit full/absolute paths to files with errors (true by default) 
//absolutePaths true 

// if true, check all issues, including those that are off by default 
checkAllwarnings true 

// if true, treat all warnings as errors 

warningsAsErrors true 

// turn off checking the given issue id's 

disable 'TypographyFractions', 'TypographyQuotes' 

// turn on the given issue id's 

enable 'RtlHardcoded','RtlCompat', 'RtlEnabled' 

// check *only* the given issue id's 

check 'NewApi', 'InlinedApi' 

// if true, don't include source code lines in the error output 

noLines true 

// if true, show all locations for an error, do not truncate lists, etc. 
showAll true 

// Fallback lint configuration (default severities, etc.) 

lintConfig file("default-lint.xml") 

// if true, generate a text report of issues (false by default) 

textReport true 

// location to write the output; can be a file or 'stdout' 

textOutput 'stdout' 

// if true, generate an XML report for use by for example Jenkins 

xmlReport false 

// file to write report to (if not specified, defaults to lint-results.xml) 
xmlOutput file("lint-report.xml") 

// if true, generate an HTML report (with issue explanations, sourcecode, etc) 
htmlReport true 

// optional path to report (default will be lint-results.html in the builddir) 
htmlOutput file("lint-report.html") 


// set to true to have all release builds run lint on issues with severity-fatal 
// and abort the build (controlled by abortOnError above) if fatal issues are found 
checkReleaseBuilds true 


Lint 支 持 





// Set the severity of the given issues to fatal (which means they will be 

// checked during release builds (even if the lint target is not included) 
fatal 'NewApi', 'InlineApi' 

// Set the severity of the given issues to error 

error 'Wakelock', 'TextViewEdits' 

// Set the severity of the given issues to warning 

warning 'ResourceAsColor' 

// Set the severity of the given issues to ignore (same as disabling the check) 
ignore 'TypographyQuotes' 
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6 构建 变种 版 本 


新 构建 系统 的 目标 之 一 就 是 为 同一 个 应 用 创建 不 同 的 版 本 。 
主要 有 两 个 使 用 场景 : 


1. 同一 个 应 用 的 不 同 版 本 。 比 如 一 个 免费 的 版 本 和 一 个 付费 的 专业 版 本 。 

2. 同一 个 应 用 被 打包 成 多 个 不 同 的 apk 以 发 布 到 Google Play 商店 。 详 情 请 见 
http://developer.android.com/google/play/publishing/multiple-apks.html 

3. 综合 第 1 条 和 第 2 条 。 


我 们 的 目标 就 是 基于 同一 个 工程 生成 不 同 的 APK， 而 不 是 使 用 一 个 单独 的 库 工程 和 两 个 以 上 的 应 用 工程 组 合生 成 APK 的 方 


式 。 





构建 变种 版 本 
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6.1 产品 定制 


一 个 product flavor 定义 了 可 以 通过 工程 构建 应 用 的 自 定义 版 本 。 一 个 独立 的 工程 可 以 定义 不 同 的 flavor 改 变 生 成 的 应 用 。 


这 种 被 设计 的 新 概念 对 于 版 本 间 差 异 非 常 小 的 时 候 很 有 用 。 如 果 “ 这 是 同一 个 应 用 吗 ? "的 答案 是 肯定 的 话 ， 那 么 这 种 方式 的 
确 比 使 用 库 工 程 的 方式 要 好 得 多 。( 译 者 注 : 以 前 的 方法 要 生成 多 个 包 ， 可 能 是 从 采用 多 个 不 同 的 应 用 工程 + 一 个 库 工程 的 方 
式 ， 现 在 这 种 新 的 方式 比 我 们 以 前 的 老 方式 好 多 了 ) 


Product flavors 是 通过 productFlavors DSL 容 器 定义 的 : 


android { 


productFlavors { 
flavori { 
I 
flavor2 { 


} 


这 里 创建 了 两 个 flavors， 分 别 是 flavor1 和 flavor2 . 注意 : flavors 的 名 字 不 能 和 已 存在 的 Build Type 名 字 或 者 androidTest 
sourceSet 冲突 。 
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6.2 构建 类 型 + 产品 定制 = 构建 变种 版 本 


正如 我 们 前 面 看 到 的 ， 每 一 个 Build Type 都 会 生成 一 个 新 的 APK。 

Product Flavors 也 是 这 么 做 的 : 工程 的 输出 将 会 尽 可 能 的 组 合 Build Types 和 Product Flavors 的 输出 。 
每 一 种 组 合 (Build Type, Product Flavon 就 是 构建 变种 

比如 ， 以 默认 的 debug 和 release Build Types 为 例 ， 上 面 的 例子 会 生成 四 个 Build Variants : 


e Flavor1 - debug 
e Flavor1 - release 
e Flavor2 - debug 
e Flavor2 - release 


没有 flavors 的 工程 仍然 是 有 Build Variants 的 ， 只 是 使 用 的 是 默认 的 flavor 和 配置 ， 并 且 没 有 名 字 ， 所 以 variants 的 列表 看 


起 来 和 Build Types 列表 一 样 。 





3r 


类 型 + 产品 定制 = 构建 变种 版 本 
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EX r3 
6.3 产品 定制 配置 
每 一 个 flavors 都 可 以 通过 一 个 闭 包 配 置 : 


android { 


defaultConfig { 
minSdkVersion 8 
versionCode 10 


J 


productFlavors { 
flavori { 
packageName "com.example.flavori" 
versionCode 20 


} 

flavor2 { 
packageName "com.example.flavor2" 
minSdkVersion 14 

j 


要 知道 的 是 android.productFlavors.* 是 ProductFlavor 类 型 的 ， 和 android.defaultConfig 对 象 具 有 相同 的 类 型 ， 者 意味 
着 他 们 有 相同 的 属性 。 





defaultConfig 为 所 有 的 flavor 提供 了 基本 的 配置 ， 每 一 个 flavor 也 都 可 以 重新 设置 覆盖 这 些 默 认 值 。 在 上 面 的 例子 中 ， 最 
终 的 配置 如 下 : 


e flavor1 
o packageName: com.example.flavor1 
o minSdkVersion: 8 
o versionCode: 20 

e flavor2 
o packageName: com.example.flavor2 
o minSdkVersion: 14 
o versionCode: 10 


通常 情况 下 ，Build Type 配置 会 覆盖 其 他 配置 ， 比 如 ，Buila Type 的 packageNameSuffix 会 追加 到 Product Flavor 的 
packageName 之 后 。 


也 有 一 些 情况 是 在 Build Type 和 Product Flavor 中 都 可 以 设置 ， 在 这 种 情况 下 ， 视 情况 而 定 。 
比如 ， signingConfig 就 是 这 么 一 个 属性 。 通过 设置 android.buildTypes.release.signingConfig ， 可 以 为 所 有 的 release 
SU 


包 共 享 相同 的 SigningConfig ， 也 可 以 单独 通过 设置 android.productFlavors..signingConfig 为 每 一 个 release 包 指 定 他 们 自 
己 的 SigningConfig* 。 
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6.4 Sourcesets 和 依赖 


类 似 Build Types , Product Flavors 也 可 以 通过 他 们 自己 的 sourceSets 控制 代码 和 资源 。 
上 面 的 例子 会 创建 4 个 sourceSets : 


e android.sourceSets.flavor1 ， 位 置 是 src/flavor1/ 
e android.sourceSets.flavor2 ， 位 置 是 src/flavor2/ 
e android.sourceSets.androidTestFlavor1 ， 位 置 是 src/androidTestFlavor1/ 





e android.sourceSets.androidTestFlavor2 ， 位 置 是 src/androidTestFlavor2/ 
这 些 sourceSets 和 android.sourceSets.main 以 及 Build Type sourceSet 一 起 构建 APK。 
当 人 处理 所 有 的 sourcesets 以 构建 一 个 单独 的 APK 的 时 候 ， 下 面 的 规则 会 被 应 用 : 


e 所 有 的 源 代码 (src/*/java) 会 以 多 文件 夹 的 方式 一 起 被 使 用 生成 一 个 输出 。 


e 所 有 Manifest 文 件 会 合并 成 一 个 manifest 文件 。 这 人 允许 Product Flavors 有 一 些 不 同 的 组 件 定义 或 者 权限 声明 ， 类 似 于 


Build Types 。 


e 所 有 的 资源 ( Android res 和 assets ) 都 会 遵循 优先 级 覆盖 的 原则 ， Build Type 会 覆盖 Product Flavorg ， 最 后 又 都 会 覆盖 


main sourceSet. 


e 每 一 个 Build Variant 会 基于 资源 生成 他 们 自己 的 R 类 (或 者 生成 其 他 的 源 代码 )，variant 之 间 不 


A 
会 共 


最 后 ， 像 Build Types, Product Flavors 也 可 以 有 他 们 自己 的 依赖 。 上 比如 ， 如 果 flavor 用 来 生成 一 个 


app， 其 中 一 个 flavor 可 能 需要 依赖 一 个 广告 SDK， 另 外 一 个 刘 不 需要 。 


dependencies { 
flavoriCompile "..." 


J 


在 这 种 特定 的 情况 下 ， src/flavori/AndroidManifest.xml 文件 可 能 需要 包含 访问 网 络 的 权限 声明 。 
此 外 ， 也 会 为 每 一 个 variant 创建 一 个 sourcesets : 


e android.sourceSets.flavor1Debug ,位 置 是 src/flavor1Debug/ 
e android.sourceSets.flavor1Release ,位 置 是 src/flavor1Release/ 
e android.sourceSets.flavor2Debug ,位 置 是 src/flavor2Debug/ 
e android.sourceSets.flavor2Release ,位 置 是 src/flavor2Release/ 


这 些 sourcesets 拥有 比 build type 更 高 的 优先 级 ， 并 且 人 允许 在 variant 级 别 上 做 一 些 定制 。 


Sourcesets 和 依赖 





= 
、 子 o 


告 ap 和 一 个 付费 的 
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6.5 构建 和 任务 


我 们 在 前 面 说 过 ， 每 一 个 Build Type 都 会 创建 它 自己 的 assemble 任务 ,但 是 Build Variants 的 任务 则 是 Build Type 和 
Product Flavor 的 组 合 。 


当 Product Flavors 被 使 用 的 时 候 ， 更 多 的 assemble-type 任务 被 创建 ， 他 们 是 : 


1. assemble 允许 直接 构建 一 个 variant 版 本 。 例 如 assembleFlavoriDebug 


2. assemble 允许 根据 给 定 的 Build Type 构建 所 有 的 APK。 例 如 assembleDebug 会 同时 构建 Flavor1Debug 和 
Flavor2Debug 两 个 variant 版 本 。 


3. assemble 允许 根据 给 定 的 flavor 构建 所 有 的 APK。 例 如 assembleFlavor1 会 同时 构建 Flavor1Debug 和 
Flavor1Release 两 个 variant 版 本 。 


assemble 任务 会 尽 可 能 的 构建 所 有 variant 版 本 。 





构建 和 任务 
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6.6 测试 

测试 多 flavor 工程 和 测试 普通 的 工程 差不多 。 

androidTest sourceset 对 所 有 的 flavor 来 说 是 通用 的 测试 ， 而 每 个 flavor 也 可 以 有 他 们 自己 的 测试 。 
正如 前 面 所 提 到 的 ， 每 一 个 flavor 都 可 以 创建 自己 的 测试 sourceSets : 


e android.sourceSets.androidTestFlavor1 ， 位 src/androidTestFlavor1/ 


e android.sourceSets.androidTestFlavor2 ， 位 src/androidTestFlavor2/ 


同样 的 ， 他 们 也 可 以 有 他 们 自己 的 依赖 : 


dependencies { 
androidTestFlavoriCompile "..." 


} 


运行 测试 可 以 通过 主 的 deviceCheck 引导 任务 ， 当 使 用 flavor 的 时 候 ， 也 可 以 通过 主 的 androidTest 引导 任务 来 执行 。 
每 一 个 flavor 都 有 他 们 自己 运行 测试 的 任务 : androidTest\。 例 如 : 


e androidTestFlavor1Debug 
e androidTestFlavor2Debug 


同样 的 ， 每 一 个 variant 也 都 有 测试 APK 任 务 、 安 装 以 及 卸载 任务 : 


e assembleFlavor1Test 
e installFlavor1Debug 
e installFlavor1Test 

e uninstallFlavoriDebug 


最 终 的 HTML 报 告 会 根据 flavor 合并 生成 。 
测试 结果 以 及 报告 的 位 置 如 下 ， 第 一 个 是 每 个 flavor 的 结果 ， 然 后 是 合并 起 来 的 : 


build/androidTest-results/flavorsA 


build/androidTest-results/all/ 


build/reports/androidTests/flavorsY 


build/reports/androidTests/all/ 





自 定义 路 径 的 话 ， 也 只 是 改变 根 目 录 ， 仍 然 会 创建 每 个 flavor 的 子 文件 夹 并 且 合 并 测试 结果 以 及 报告 。 


测试 


41 


Android Gradle 插件 中 文 指南 


6.7 多 种 定制 的 版 本 


有 些 情况 下 ， 人 们 想 基于 不 同 的 标准 创建 同一 应 用 的 几 个 不 同 的 版 本 。 例如 ，Google Play 里 的 multi-apk 支持 4 种 不 同 的 过 
滤器 。 为 每 一 个 过 滤器 创建 不 同 的 APK 就 需要 用 到 多 维度 的 Product Flavor 了 。 


考虑 到 一 个 游戏 有 一 个 演示 版 本 和 一 个 付费 版 本 ， 并 且 在 multi-apk 支持 中 需要 用 到 ABI 过 滤器 。3 个 ABI 和 两 个 版 本 的 情况 
下 ， 就 会 有 6 个 APK 生成 (没有 计算 不 同 的 Build Type 的 variant 版 本 )。 然而 ， 对 于 三 个 ABI 来 说 ， 他 们 的 付费 版 本 的 代码 都 
是 一 样 的 ， 因 此 只 是 简单 的 创建 6 个 flavor 并 不 是 一 个 好 办 法 。 相反 的 ， 使 用 两 个 flavor 维度 ， 并 且 自 动 构建 所 有 可 能 的 
variants, 


这 个 功能 通过 Flavor Dimensions 能 实现 。Flavors 会 被 指定 到 特定 的 维度 。 


android ( 


flavorDimensions "abi", "version" 


productFlavors { 
freeapp { 
flavorDimension "version" 


} 
x86 { 

flavorDimension "abi" 
j 


android.flavorDimensions 数据 定义 了 可 能 用 到 的 唯 独 以 及 顺序 。 每 一 个 定义 的 Product Flavor 都 会 被 指定 一 个 纬度 。 


从 Product Flavors [freeapp, paidapp]. [x86, arm, mips], [debug, release] Build Types 维度 ， 会 有 以 下 build variant 被 创 
建 : 


e x86-freeapp-debug 
e x86-freeapp-release 
e arm-freeapp-debug 
e arm-freeapp-release 
e mips-freeapp-debug 
e mips-freeapp-release 
e x86-paidapp-debug 
e x86-paidapp-release 
e arm-paidapp-debug 
e arm-paidapp-release 
e mips-paidapp-debug 
e mips-paidapp-release 


通过 android.flavorDimensions 定义 的 维度 的 顺序 是 非常 重要 的 。 
每 一 个 variant 都 会 被 如 下 几 个 Product Flavor 对 象 配置 : 
e android.defaultConfig 


e abi 维度 
e version 维度 
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维度 的 顺序 决定 了 哪 一 个 flavor 会 覆盖 哪 一 个 flavor， 这 对 于 资源 来 说 非常 重要 ， 因 为 flavor 会 蔡 换 掉 定义 在 低 优先 级 flavor 
中 的 值 。 


flavor 维度 首先 使 用 高 优先 级 的 定义 。 在 这 里 是 : 


abi > version > defaultConfig 


Multi-flavors 工程 也 有 人 额外 的 sourcesets。 类 似 variant 的 sourcesets， 只 是 没有 build type. 


e android.sourceSets.x86Freeapp ， 位 置 是 src/x86Freeapp/ 
e android.sourceSets.armPaidapp ， 位 置 是 src/armPaidapp/ 


e 等 等 … 


这 人 允许 你 在 flavor-combination 级 别 上 进行 定制 。 他 们 比 普通 的 flavor sourcesets 优先 级 高 ， 但 是 比 build type sourcesets 
优先 级 低 。 
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7 高 级 构建 定制 
7.1 构建 选项 


7.1.1 Java 编译 选项 


android ( 
compileOptions ( 
sourceCompatibility - "1.6" 
targetCompatibility - "1.6" 
J 
i 


默认 值 是 1.6。 这 个 设置 会 影响 所 有 编译 java 源 代码 的 任务 。 


Java 编 译 选 项 
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7.1.2 aapt 选 项 


android ( 
aaptOptions { 
noCompress 'foo', 'bar' 
ignoreAssetsPattern "!.svn:!.git:!.ds store:!*.scc:.*:«dir» *:!CVS:!thumbs.db:!picasa.ini:!*-" 


这 会 影响 所 有 使 用 appt 的 任务 。 


aapt 选 项 
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7.1.3 deX 选 项 


android ( 
dexOptions { 
incremental false 
preDexLibraries - false 
jumboMode - false 
javaMaxHeapSize "2048M" 


这 会 影响 所 有 使 用 dex 的 任务 


dex 选 项 
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7.2 操纵 任务 


普通 的 Java 工程 有 一 个 有 限 的 任务 集合 ， 这 些 任务 相互 配合 创建 一 个 输出 。 classes 是 一 个 编译 Java 源 代码 的 任务 。 在 
build.gradle 中 通过 脚本 访问 和 使 用 classes 任务 是 很 简单 的 。 可 以 通过 project.tasks.classes 快捷 访问 。 


对 于 Android 工程 来 说 就 比较 复杂 了 ， 因 为 可 能 有 很 多 相同 的 任务 ， 他 们 的 名 字 是 基于 Build Types 和 Product Flavors 生成 
的 。 


为 了 解决 这 个 问题 ， android 对 象 提 供 了 两 个 属性 : 


e applicationVariants (仅仅 适用 于 app plugin ) 
e libraryVariants (仅仅 适用 于 library plugin ) 
e testVariants (两 种 plugin 都 适用 ) 


ApplicationVariant, LibraryVariant, and TestVariant 这 三 个 对 象 都 会 分 别 返 回 一 个 DomainObjectCollection。 
请 注意 访问 这 些 集合 中 的 任何 一 个 都 会 触发 生成 所 有 的 创建 。 这 意味 着 访问 这 些 集合 后 无 须 重 新 配置 就 会 产生 。 
DomainObjectCollection 允许 直接 的 访问 所 有 对 象 ， 或 者 通过 更 为 方便 的 过 滤器 访问 。 


android.applicationVariants.each { variant -> 


} 


这 三 个 variant 类 都 具有 以 下 属性 : 


属性 名 属性 类 型 说 明 
name String variant 的 名 字 ， 必 须 是 唯一 的 。 
description String variant 的 可 读 性 的 描述 
dirName String Pa ee 须 是 惟一 的 。 可 能 还 不 止 一 
baseName String variant 输 出 的 的 基本 名 称 ， 必 须 是 唯一 的 。 
outputFile File variant 的 输出 ， 是 一 个 可 读 写 的 属性 
processManifest ProcessManifest 处 理 manifest 的 任务 
aidlCompile AidlCompile 编译 AIDL 文 件 的 任务 
renderscriptCompile RenderscriptCompile 编译 Renderscript 文 件 的 任务 
mergeResources MergeResources 合并 资源 的 任务 
mergeAssets MergeAssets 合并 资源 的 任务 
processResources ProcessAndroidResources 处 理 和 编译 资源 的 任务 
generateBuildConfig GenerateBuildConfig 生成 BuildConfig 类 的 任务 
javaCompile JavaCompile 编译 Java 代 码 的 任务 
processJavaResources Copy 处 理 Java 资 源 的 任务 
assemble DefaultTask 这 个 variant 的 assemble 引 导 任 务 


ApplicationVariant 类 还 有 以 下 属性 : 
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属性 名 属性 类 型 说 明 
buildType BuildType variant 的 BuildType。 
productFlavors List\ variant 的 ProductFlavors， 不 能 为 空 ， 但 可 以 是 空 值 
mergedFlavor ProductFlavor android.defaultConfig 和 variant.productFlavors 合 并 
signingConfig SigningConfig 这 个 variant 使 用 的 SigningConfig 对 象 
isSigningReady boolean 如 果 为 true 则 说 明 variant 已 经 具备 签名 所 需 的 一 切 信息 
testVariant BuildVariant 将 会 测试 这 个 variant 的 TestVariant 
dex Dex dex 代 码 的 任务 ， 如 果 variant 是 一 个 库 可 以 为 null 


packageApplication PackageApplication 生成 最 终 AP 看 的 任务 ， 如 果 variant 是 一 个 库 可 以 为 null 


Zipilign ZipAlign zip 压 缩 apk 的 任务 ， 如 果 variant 是 一 个 库 或 者 APK 不 能 被 签名 可 以 为 


null 
install DefaultTask 安装 任务 ， 可 以 为 null。 
uninstall DefaultTask HREJ 
LibraryVariant 类 还 有 以 下 属性 : 
属性 名 属性 类 型 说 明 
buildType BuildType variant 的 BuildType 
mergedFlavor ProductFlavor 就 是 defaultConfig 
testVariant BuildVariant 将 要 测试 这 个 variant 的 Build Variant 
packageLibrary Zip 把 库 打 包 成 一 个 AAR 存 档 的 任务 ， 如 果 不 是 一 个 库 值 为 Null 
TestVariant 类 还 有 以 下 属性 : 
属性 名 属性 类 型 说 明 
buildType BuildType variant 的 BuildType。 
productFlavors List\ variant 的 ProductFlavors， 不 能 为 空 ， 但 可 以 是 空 值 
mergedFlavor ProductFlavor android.defaultConfig 和 variant.productFlavors 合 并 
signingConfig SigningConfig 这 个 variant 使 用 的 SigningConfig 对 象 
isSigningReady boolean 如 果 为 true 则 说 明 variant 已 经 具备 签名 所 需 的 一 切 信息 
testVariant BaseVariant 将 会 测试 这 个 variant 的 BaseVariant 
dex Dex dex 代 码 的 任务 ， 如 果 variant 是 一 个 库 可 以 为 null 
packageApplication PackageApplication 生成 最 终 AP 看 的 任务 ， 如 果 variant 是 一 个 库 可 以 为 null 
1 "71 人 |= 7x av Kk ab Ak ~ 
zipAlign ZipAlign P ELE 如 果 variant 是 一 个 库 或 者 APK 不 能 被 签名 可 以 
install DefaultTask 安装 任务 ， 可 以 为 null。 
uninstall DefaultTask HRES 
connectedAndroidTest DefaultTask 在 已 连接 的 设备 上 运行 android 测 试 的 任务 
providerAndroidTest DefaultTask 使 用 扩展 的 APl 运 行 android 测 试 的 任务 


Android 特 定 任务 类 型 的 API 
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e ProcessManifest 
o File manifestOutputFile 
e AidlCompile 
o File sourceOutputDir 
e RenderscriptCompile 
o File sourceOutputDir 
o File resOutputDir 
e MergeResources 
o File outputDir 
e MergeAssets 
o File outputDir 
e ProcessAndroidResources 
o File manifestFile 
o File resDir 
o File assetsDir 
o File sourceOutputDir 
o File textSymbolOutputDir 
o File packageOutputFile 
o File proguardOutputFile 
e GenerateBuildConfig 
o File sourceOutputDir 
e Dex 
o File outputFolder 
e PackageApplication 
o File resourceFile 
o File dexFile 
o File javaResourceDir 
o File jniDir 
o File outputFile 
m Tochange the final output file use "outputFile" on the variant object directly. 
e ZipAlign 
o File inputFile 
o File outputFile 
m To change the final output file use "outputFile" on the variant object directly. 


每 一 个 任务 类 型 的 API 都 会 因为 Gradle 的 工作 方式 以 及 Android plugin 的 设置 受到 限制 。 首先 ，Gradle 限制 只 能 配置 任务 


的 输入 /输出 以 及 一 些 可 选 的 标志 。 所 以 ， 这 里 的 这 些 任 务 只 能 定义 输入 /输出 。 


其 次 ， 大 多 数 任务 的 输入 并 不 唯一 ， 通 常会 混合 sourceSets，Build Types 以 及 Product Flavors。 为 了 保持 构建 简单 以 及 可 


读 性 ， 我 们 的 目标 是 让 开发 者 通过 DSL 通过 这 些 对 象 修改 构建 ， 而 不 是 深入 的 了 解 任务 的 输入 和 选项 进而 修改 它们 。 


还 要 注意 的 是 ， 除 了 ZipAlign 任务 类 型 ， 其 他 所 有 的 任务 都 需要 设置 私有 数据 让 他 们 运行 。 这 就 意味 着 不 能 基于 这 些 类 型 


动 的 创建 新 的 任务 。 


对 于 Gradle 的 任务 (DefaultTask, JavaCompile, Copy, Zip) ， 请 参考 Gradle 文档 。 


T 


操纵 任 





务 
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7.3 BuildType and Product Flavor 的 属性 参考 


即将 推出 。 


对 于 Gradle 的 任务 (DefaultTask, JavaCompile, Copy, Zip) ， 请 参考 Gradle 文档 。 


n 





BuildType and Product Flavor 的 属性 参考 
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7.4 使 用 sourceCompatibility 1.7 


基于 Android KitKat (buildToolsVersion 19) 开 发 的 时 候 ， 你 能 用 diamond operator, multi-catch, strings in switches, try with 
resources 等 等 这 些 新 的 特性 。 要 做 到 这 些 ， 你 需要 把 下 面 的 配置 添加 到 你 的 构建 文件 中 : 


android ( 
compileSdkVersion 19 
buildToolsVersion "19.0.0" 


defaultConfig { 
minSdkVersion 7 
targetSdkVersion 19 
J 


compileOptions { 


sourceCompatibility JavaVersion.VERSION 1 7 
targetCompatibility JavaVersion.VERSION 1 7 


需要 注意 的 是 你 也 可 以 把 minSdkVersion 设置 为 19 之 前 的 版 本 ， 这 样 的 话 你 只 能 使 用 除 try with resources 之 外 的 语言 特 
性 。 如 果 你 想 使 用 try with resources， 你 需要 设置 minSdkVersion 为 19。 


你 还 需要 确认 Gradle 使 用 的 JDK1.7 或 者 之 后 的 版 本 。 (并 且 Android Gradle plugin 同样 也 需要 0.6.1 或 者 之 后 的 版 本 ) 








使 


M 
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